perm filename SNAIL.MJC[S,DOC] blob
sn#354909 filedate 1978-05-12 generic text, type C, neo UTF8
COMMENT ⊗ VALID 00021 PAGES
C REC PAGE DESCRIPTION
C00001 00001
C00004 00002 S N A I L
C00007 00003 SNAIL: EDIT-Class Commands
C00014 00004 SNAIL: COMPILE-Class Commands
C00016 00005 SNAIL: DOCUMENT-Type COMPILE-Class Commands
C00018 00006 SNAIL: LOADBUF-Type COMPILE-Class Commands
C00023 00007 SNAIL: COMPILE-Type COMPILE-Class Commands
C00035 00008 SNAIL: More on File Names
C00037 00009 SNAIL: More on Switches
C00039 00010 SNAIL: Concatenation of Source Files
C00042 00011 SNAIL: Producing Symbolic Listings
C00046 00012 SNAIL: Generating Core Images and DMP Files
C00051 00013 SNAIL: Library Searches
C00054 00014 SNAIL: Alternate Processor Features
C00058 00015 SNAIL: Translator Switches
C00060 00016 SNAIL: Loader Switches
C00062 00017 SNAIL: Command Files
C00065 00018 SNAIL: CREF Command
C00066 00019 SNAIL: Switch Function Summary
C00070 00020 SNAIL: LOADER Switches and LINK Equivalents
C00074 00021 SNAIL: Error Messages
C00079 ENDMK
C⊗;
S N A I L
This documentation is extracted from Appendix 1 of the Monitor Command
Manual, which can be found online in the file MONCOM.BH[S,DOC] or in print
as SAILON 54.5.
SNAIL is a program which interprets certain monitor commands for editing
files, compiling and loading programs, and loading the line editor buffer.
It simplifies these tasks when necessary by expanding concise user commands
into the different forms used by editors, language processors, and the
loaders. Without user intervention, SNAIL will run the correct language
processors to translate the user's files, and will run a loader to create an
executable core image containing the user's program. SNAIL also provides a
convenient means of communication between editors and other processors.
(You may occasionally encounter a bug in SNAIL. When this unfortunate event
happens, you should run TSNAIL, a version of SNAIL which includes RAID and
various debugging routines. To use TSNAIL, type R TSNAIL to the monitor,
then type the SNAIL command in answer to the asterisk prompt. TSNAIL pauses
occasionally to display interesting information; type a blank to continue
processing. When TSNAIL exits, save the core image and notify MJC of the
bug.)
SNAIL knows about certain standard processors. These are the editors: SOS
and TECO; the compilers: SAIL, FAIL, F40 (FORTRAN), MACRO, and PAL; the
document compilers: PUB and POX; the debuggers: BAIL, RAID, and DDT; and the
loaders: LOADER and LINK.
The E editor includes within it the SNAIL functions, so its "SNAIL" commands
run E directly rather than via the SNAIL program. Nevertheless, the E
commands are included here because they are operationally similar.
The SNAIL commands are divided into three classes: EDIT, COMPILE, and CREF.
SNAIL: EDIT-Class Commands
There are six EDIT-class commands, two for each of the three commonly used
editors:
Command Name
Program Create File Edit File
E CETV ETV
SOS CREATE EDIT
TECO MAKE TECO
CREATE and MAKE
These commands take a file name as the argument. SNAIL will call the editor
and tell it to initialize the file of that name. For CREATE, SOS is started
in line insertion mode. TECO (the MAKE command) will be initialized to
write on the specified file.
EDIT and TECO
These commands take a file name (with optional project-programmer name) as
the argument. SNAIL remembers the name of the last file that was edited in
a tmpcor file named ED. (A tmpcor file is a simulated file kept in core by
the monitor until the job is logged out.) If an EDIT-class command is given
without an argument, SNAIL will use the argument that it remembered.
If no extension is specified in the argument and no file with the given name
and blank extension can be found, then the user's directory is searched for
any file with the given name and one of several standard extensions. The
standard extensions are searched in the order:
FAI SAI F4 PUB POX MAC LSP LAP PAL WRU NSA OSA LST CMD TXT
If none of these is found, the first file listed in the directory with the
correct name and any extension is edited.
If a user specifies a disk area other than his own current (alias) area,
then the edited file will be put on his disk area and the source (from the
other area) will not be changed.
The editors have a read-only mode in which files may be examined by using
editor commands, but not changed. To get read-only mode type /R after the
file name in the edit command (e.g., ETV M.SAI/R). Read-only mode in SOS
prohibits any commands that would change the file. In the E editor, the
mode may be changed from read-only to read-write at any time.
CETV and ETV
These are the create and edit commands for the E editor. They do not run
the SNAIL program; instead, E itself simulates the SNAIL functions. There
are some differences between these and the other editor commands:
1. The command can include /nP and /nL switches for page and line numbers
and the /N switch for no-directory mode as well as /R for read-only. E
saves its position in the file when it exits, so a later ETV command with no
argument will continue the edit from the same point in the file.
2. If you specify a PPN with the filename given, E will let you edit the
file on that disk area instead of copying the file to your current area as
the other editors do.
READ
The READ command starts E in a special mode, called book mode, used to read
long files over an extended time period. In this mode, E does several
things differently from the normal editing procedure:
1. If there is a file with the name in the READ command, the extension BKP,
and a PPN matching either that given in the command, your ALIAS PPN, or your
login PPN (tried in that order), it is used as a SNAIL file to determine
where to start editing the specified file. This "bookmark" file is not
deleted by LOGOUT, so you can continue reading at a later session. The
file, if found, is updated when you exit from E; if there was no BKP file,
one is created on your (alias) area when you exit. However, if you exit
from E while on the last page of the file, the BKP file will be deleted (E
assumes you have finished reading the book in this case).
2. A READ command with no argument uses tmpcor files like the ETV command
does, but the tmpcor filename used is different, so you can alternate ETV
and READ commands for different files with no confusion.
3. E does not allow you to modify the file when using book mode.
SNAIL: COMPILE-Class Commands
There are three types of COMPILE-class commands: COMPILE-type commands,
which abbreviate a series of commands to compilers (and other language
processors) and loaders; DOCUMENT-type commands, which process a document;
and LOADBUF-type commands, which load the line editor buffer with a sequence
of commands much like the DO processor (see Section 5.7 of the Monitor
Command Manual, in file MONCOM.BH[S,DOC]). Each COMPILE-class command, if
given with arguments, remembers both the command and the arguments in a
tmpcor file named CM. This is useful because all the editors allow an
exit-and-go command (in SOS, the G command; in E, the CONTROL-X GO command;
in TECO, the EG command). The exit-and-go feature runs SNAIL in a special
way which makes SNAIL re-execute the command that it remembered.
SNAIL: DOCUMENT-Type COMPILE-Class Commands
The DOCUMENT-type COMPILE-class commands are the easiest to describe. These
commands, PUB and POX, run the document processors PUB and POX. Both
commands take a file name as an argument, with optional switches. If an
extension is specified with the file name, that file is processed by the
appropriate document processor. If, on the other hand, no extension is
specified with the file name, the user's directory is searched first for the
file with the given name and extension .PUB or .POX, depending on the
command, then for the file with the given name and no extension. Whichever
of those files is found first is the one which will be processed by the
document processor.
Switches to the document processor may be specified in parentheses
immediately following the file name.
Examples of use:
POX FOO.POX
PUB FOO.PUB(LH)
PUB XXX
The last of these will run PUB on the file XXX.PUB if it exists, otherwise
it will run PUB on XXX.
SNAIL: LOADBUF-Type COMPILE-Class Commands
The second type of COMPILE-class commands are the LOADBUF-type commands.
There are three such commands: RER, RERUN, and PROCESS. These commands
incorporate some of the features of the DO processor, allowing the user to
take advantage of the exit-and-go feature of the editors for an arbitrary
sequence of commands without paying the penalty of running an extra
processor.
The RER and RERUN commands are similar in form. Both are followed by a
processor name, an optional core size for the processor, a double-arrow, and
a string (called the object string) terminated by a line feed. SNAIL swaps
control to the designated processor after loading the object string into the
line editor buffer. The only difference is that the processor in the RER
command is retrieved from the SYS: disk area, while the processor in the
RERUN command is retrieved from the user's own disk area, or one that he
specifies explicitly. This distinction is the same one made between the R
and RUN monitor commands.
The PROCESS command is followed by a double-arrow and an object string,
terminated by a line feed. After loading the object string into the line
editor buffer, SNAIL exits.
SNAIL preprocesses the object string for all three commands by replacing
occurrences of the character double-arrow ("↔") by a carriage return-line
feed. The DO processor also does this. However, the other
character-replacement features of DO are not currently implemented.
The RER and RERUN commands are compatible in the following way. If a RER
command with its arguments has been previously given by the user and saved
by SNAIL in a tmpcor file, and the user subsequently types RERUN without any
arguments, the effect will be that of typing RERUN with the arguments of the
previous RER command. That is, the processor will be retrieved from the
user's disk area instead of from the system disk area. Analogously, if a
RER command with no arguments is given and the command file contains a RERUN
command, the designated processor is retrieved from the system disk area
instead of the user-specified disk area. In either case, the core size and
object string are processed as described above.
If a PROCESS command is given with no arguments, the command tmpcor file
must contain a PROCESS command. If a RER or RERUN command is given with no
arguments, the command tmpcor file must contain a RER or RERUN command.
Otherwise an error message will be printed and the line editor buffer will
not be loaded.
Examples of use:
RER IL↔(DSKIN FOO)↔
PROCESS↔R IL↔(DSKIN FOO)↔
RERUN IL[UCI,SYS]↔(DSKIN FOO)
The first two examples will do the same thing. The third example could be
used to allow alternating use of RER and RERUN to compare the current
version of ILISP with a new version.
SNAIL: COMPILE-Type COMPILE-Class Commands
The last type of COMPILE-class command to be described is the COMPILE-type
command. There are six COMPILE-type commands: COMPILE, LOAD, PREPARE,
DEBUG, EXECUTE, and TRY. Following the command, the user lists files which
are to be compiled or loaded.
All COMPILE-class commands normally cause compilation of the specified
source files. All but the COMPILE command may cause execution of a loader
(LOADER or LINK) to create a core image, possibly including a debugger. The
table below summarizes the actions of the COMPILE-type commands.
REL file Core Image Debugger Execution
COMPILE yes
LOAD yes yes
PREPARE yes yes yes
EXECUTE yes yes starts the user program
TRY yes yes yes starts the user program
DEBUG yes yes yes starts the debugger
The COMPILE command takes as arguments one or more file descriptors,
separated by commas. SNAIL will cause the appropriate translator to be used
for each of the files. The COMPILE command does not produce a core image;
to get an executable core image one of the other COMPILE-type commands must
be used.
LOAD does a COMPILE if necessary and then starts a loader (LOADER or LINK).
The loader takes the .REL files that were generated by the compilers and
combines them into an executable core image. When the loader is done, it
exits to the monitor. This command makes a core image but does not start
it. If any SAIL program is loaded, the loader will be instructed to request
the current SAIL segment.
PREPARE is like LOAD, but a debugger (BAIL for SAIL programs, RAID for other
programs when the user is at a display, and otherwise DDT) is loaded with
the user's program.
EXECUTE is like LOAD, but instead of exiting, the loader starts the program
it loaded at its specified starting address.
The TRY command is like EXECUTE, but it loads a debugger (BAIL, RAID, or
DDT, as in the PREPARE command) with the user program. Execution starts at
the program's starting address.
DEBUG is like TRY except that rather than starting the user's program it
starts the debugger (RAID or DDT -- if the debugger is BAIL this command is
treated exactly the same as TRY). The user may give commands to the
debugger to start his program, to plant breakpoints, etc.
SNAIL writes tmpcor files for each processor involved in compiling or
loading the files specified in the user's command string. SNAIL also
attempts to minimize unnecessary compilations by checking the creation dates
for the files the user wants compiled; for example, if the command was
EXECUTE X1.SAI,X2.SAI
and the file X1.REL has a later creation date than the file X1.SAI, SNAIL
assumes that X1.SAI has not been changed since it was last compiled, and
omits X1.SAI when it tells SAIL which files to compile. If the REL file and
the source file have the same time written, then the file is compiled again
for safety, in case the source has been changed.
The user can override SNAIL's date-checking by specifying certain switches.
A SNAIL switch is selected by including a slash ("/") followed by the
appropriate switch name. Switches which affect the date-checking actions of
SNAIL are the following, where an asterisk ("*") following a switch
indicates that that switch selection is the default for SNAIL:
/COMPILE Force recompilation without checking the dates of .REL
files.
/-COMPILE * Check dates of both source, .DMP, and .REL files and act
accordingly.
/REL Force loading from the .REL file if it exists.
/-REL * Check dates of both source, .DMP, and .REL files and act
accordingly.
/NOLOAD Don't issue a loading request for this file.
/-NOLOAD * Issue a loading request for the file if one is called for.
/LONLY (Implies /COMPILE, /NOLOAD, and /NODMP.) A listing should
be made for this file, but no load request for it should be
issued.
/-LONLY * Treat this file normally.
/CONLY (Implies /COMPILE, /NOLOAD, and /NODMP.) A cross-reference
listing should be made for this file, but no load request
for it should be issued.
/-CONLY * Treat this file normally.
/LIBRARY (Implies /REL.) Force the loader to search this file as a
library.
/-LIBRARY * Treat this file normally.
/NODMP Don't include the .DMP file in date-checking or deciding
which file to give control to first. This switch has no
inverse.
SNAIL remembers the last COMPILE-type command with arguments it was given,
just as it does for DOCUMENT-type commands and LOADBUF-type commands, in a
tmpcor file named CM. This "remembering" may be turned off for COMPILE-type
commands by using the /NOCMFI switch; if this switch appears in a command,
the CM file will not be written for that command. This switch is useful
when using either a LOADBUF-type command or the DO processor, and including
within the command string another SNAIL COMPILE-class command; if /NOCMFI
were not specified, the second command would be saved in the CM file instead
of the first.
The simplest way to translate several programs is to create them with file
extensions which define the processor to be used; then give a single COMPILE
command with all these names separated by commas. (If a standard extension
is specified for a file, SNAIL cannot be convinced to use some other
processor.) Extensions which SNAIL knows about are the following:
.FAI signals a Fail program
.SAI signals a Sail program
.MAC signals a Macro program
.F4 signals a Fortran program
.PAL signals a Palx program
SNAIL does not require file extensions to be typed explicitly. For the
command COMPILE FOO, SNAIL will look for any file named FOO and check its
extension. If a file FOO is found that does have one of the standard
extensions, SNAIL will select the corresponding translator. If a file does
not have a standard extension, SNAIL can be told which translator to use by
giving that information in the command string. Switches which tell SNAIL
which translator to select are the following:
/FAIL Process this file with the Fail assembler.
/-FAIL Process this file with some translator other than Fail.
/SAIL Process this file with the Sail compiler.
/-SAIL Process this file with some translator other than Sail.
/MACRO Process this file with the Macro assembler.
/-MACRO Process this file with some translator other than Macro.
/F4 Process this file with the Fortran compiler.
/-F4 Process this file with some translator other than Fortran.
/PALX Process this file with the Palx assembler.
/-PALX Process this file with some translator other than Palx.
SNAIL: More on File Names
A project-programmer name (PPN) may be included with each file name in the
command for COMPILE-type commands, just like for other SNAIL commands. The
PPN specifies the disk area from which the file is to be read. The PPN,
enclosed in square brackets ([ and ]), usually follows a file name; in this
case the PPN applies only to the preceding term. If a PPN appears before a
file name, then that PPN is sticky (i.e., it applies to all the terms that
follow) for the rest of the command until another sticky PPN is seen.
A name followed by a colon (:) is a device name (which is sticky). Some
devices are non-directory devices (for instance, TTY: and MTA:); a file name
need not follow specification of such a device. For example, the command
COMPILE TTY:/SAIL
compiles, using the SAIL compiler, input from the user's terminal.
SNAIL: More on Switches
Switches are allowed in COMPILE-class commands by including a slash (/) and
the switch name, e.g., /LIST. Switches allow the user to select options.
In general, a switch placed before a file name is sticky. Switches placed
after a file name are not sticky; they apply only to the preceding term.
Specifying a minus ("-") before a switch turns off that switch. For
example, the command
COMPILE/FAIL A,B,C/-FAIL
will compile the files A and B using the FAIL assembler, and will compile C
using some other translator depending on extensions of files with file name
C.
SNAIL: Concatenation of Source Files
It is often desirable to break up a program into two (or more) separate
files which have only one END statement at the end of the last file. One
reason for breaking up a program is because it is very long, and it would be
inconvenient to keep and edit such a large file. Another reason for
separating a program is to allow a portion of the program text to be shared.
Several files can be processed together as one big translation by separating
their names with plus signs (+) rather than with commas. For example,
COMPILE DATA+PROGRM
treats the files DATA and PROGRM as if they were one large file and produces
one relocatable binary file, PROGRM.REL. SNAIL will not allow concatenation
of source files that specify inconsistent processors.
Normally, the REL file will have the name of the last file in the command
string; it can be given some other name by putting the desired name and an
equals sign (=) at the front of the argument list, e.g.,
COMPILE FOO=SYMS+PROGRM+IOPACK
would do one translation as if SYMS, PROGRM, and IOPACK were one large file
and produce relocatable binary output on the file FOO.REL.
Occasionally, a header file must be assembled with several other files,
e.g.,
COMPILE ACUMS+SINE,ACUMS+COSINE,ACUMS+TANGNT
The brokets (< and >) feature allows this to be done more simply:
COMPILE ACUMS+<SINE,COSINE,TANGNT>
Brokets may not be nested. Also, a plus sign may not follow a right broket;
e.g., the following command is illegal:
COMPILE <A,B,C>+ENDS
SNAIL: Producing Symbolic Listings
Assembly listings have the original code as it appears in the file plus the
octal values that the code represents with the relative locations that the
octal values go in. Assembly listings can be generated by means of a /LIST,
/LONLY, /CREF, or /CONLY switch in the command.
The /LIST and /LONLY switches will produce a file with the same name as the
REL file and extension LST. Such a file may be spooled or typed. The two
switches differ in that the /LONLY switch implies /COMPILE, /NOLOAD, and
/NODUMP; i.e., it means that the only thing to do with the file is make a
listing for it, and no REL file will be generated by the compiler for the
source file. Note that COMPILE FOO/LIST will not compile anything if a
current FOO.REL exists (this is another instance where the /COMPILE switch
is useful). The /LIST may be used as a sticky switch or it may be applied
to particular terms. The inverse switches are /-LIST and /-LONLY.
(Processors other than the assemblers may also produce listings.)
If either the /CREF switch or the /CONLY switch appears, instead of /LIST,
it generates an expanded listing that includes a list of all the symbols
(identifiers) used in the program and the line numbers on which each symbol
appears. This is called a cross-reference listing. These listing files
cannot be printed directly. Instead, they must be processed by the
cross-reference lister program, CREF. This is done by the CREF command (see
page 18). The /CONLY switch differs from the /CREF switch in that the
source file will always be compiled, and no binary file will be generated by
the compiler for the source file. The distinction between the /CREF and
/CONLY switches is the same as that for the /LIST and /LONLY switches
described above. Note: not all the processors can produce a cross-reference
listing. Consult the appropriate manual to find out if a given processor is
capable of generating one.
SNAIL: Generating Core Images and DMP Files
The commands EXECUTE, DEBUG, LOAD, PREPARE, and TRY each generate an
executable core image. Core images are made by translating source files (as
in the COMPILE command) and then running a loader (either LINK or LOADER),
which takes the REL files and produces a core image from them. For the
DEBUG, PREPARE, and TRY commands, the loader is instructed to load a copy of
RAID (or DDT if the user is at a Teletype) and the program symbol table with
the core image.
Several SNAIL switches are relevant to the selection of a loader, and to the
actions of the loader once it starts loading. These switches are listed
below. None of these switches may be negated; i.e., a minus sign may not be
used with them.
/LINK The LINK loader will be used to create the user's core image.
/LOADER The LOADER loader will be used to create the user's core image.
/BAIL If the command specified a debugger (i.e., if the command was
DEBUG, TRY, or PREPARE), BAIL will be loaded.
/RAID If the command specified a debugger, RAID will be loaded.
/DDT If the command specified a debugger, DDT will be loaded.
/MAP The absolute values of all the global symbols will be listed in
a legible way on a file named MAP.MAP; this may not work for
LOADER.
/NOSAISEGThe Sail segment will not be loaded.
/SAVE A disk dump will be made of the core image. The dump file will
have the same name as the first REL file and extension .DMP; it
can be given some other name by putting the desired name and a
left arrow (←) in the command string. /SAVE is unnecessary if
the left-arrow construct is used.
The command
TRY DUMP←SINE,COSINE/SAVE
translates the programs SINE and COSINE, producing SINE.REL and COSINE.REL.
The LOADER is run. Because the TRY command requests a debugger, RAID.REL
(or DDT.REL) is loaded from the system area. SINE.REL and COSINE.REL are
loaded next. Then the LOADER makes a dump copy of the core image in the
file DUMP.DMP and starts the program.
If there already exists a DMP file of the right name and if it has a
creation date more recent than those of the source files, no loading will be
done. Instead, the dump copy itself will be called in. Reloading may be
forced by the /NODMP or /NODUMP switch in the command line. Both an equals
sign and a left arrow may be included in a command string. For example:
COMMAND REL DMP
TRY SINE+COS/SAVE COS.REL COS.DMP
TRY DUMP←SINE+COS/SAVE COS.REL DUMP.DMP
TRY DUMP=SINE+COS/SAVE DUMP.REL DUMP.DMP
TRY FOO←DUMP=SINE+COS/SAVE DUMP.REL FOO.DMP
SNAIL: Library Searches
Several REL files may be combined into a library. A library is a special
REL file from which routines may be independently selected. Library files
are made by combining REL files together using the FUDGE2 program (which is
described in DEC documentation). For example, sine, cosine, and tangent
routines might be combined into a trig library, TRIG.REL. Then, if a
particular program used just the sine routine, instead of loading the entire
trig package it would be able to select only the sine routine. The loader
will search library files and load only the programs that are needed. The
/LIBRARY switch after the name of a library file tells SNAIL to request this
loader feature. The /LIBRARY switch may also be used as a sticky switch;
its inverse is /-LIBRARY. Suppose there is a program called NLT which uses
the sine routine that was included in TRIG.REL. Then the command
LOAD NLT,TRIG/LIBRARY will cause NLT to be loaded and TRIG to be searched.
The LOADER notices that NLT requires SINE.REL and searches TRIG.REL for it.
Suppose another program, XLT, requires routines from two library files,
TRIG.REL and IOPACK.REL, and must be loaded with another program LT. Then
any one of the following commands could do this:
LOAD XLT,LT,/LIBRARY TRIG,IOPACK
LOAD /LIBRARY XLT/-LIBRARY,LT/-LIBRARY,TRIG,IOPACK
LOAD XLT,LT,TRIG/LIBRARY,IOPACK/LIBRARY
Programs which use library files must be placed before the library file
names in the command. This is because the loader cannot know what routines
to extract from each library until it has loaded the programs that require
library routines.
SNAIL: Alternate Processor Features
Processors other than SAIL, FAIL, FORTRAN, PALX, or MACRO may be specified
by using the alternate processor feature. The switch /PROCESSOR DEV:NAME
specifies an alternate processor. In this switch, DEV (assumed to be DSK,
if absent) is the device name on which to find NAME.DMP, the core image file
of the alternate processor. Once the /PROCESSOR switch is used, SNAIL will
recognize the extension NAM (i.e., the first three letters of the processor
name) and the switch /NAME (the processor name) in the command line. A
project-programmer name or device name may be used in specifying the
alternate processor.
For example, for a user to translate the program SINE using a processor
named PROC on his disk area, he could use the command:
COMPILE SINE/PROCESSOR PROC
When a standard processor is used, it is known that it will take a text
source file and produce a binary REL file, and possibly a text LST file.
With alternate processors there is no such guarantee. An alternate
processor may process a text file into a new text file which becomes input
to a standard processor. It is possible to specify all these functions in a
single COMPILE-type command.
If an alternate processor generates a text file instead of a REL file,
loading must be inhibited. The /NOLOAD switch accomplishes this. The
/NOLOAD switch must be used for each term that does not produce a REL file
(except in the COMPILE command, which does no loading anyway). The inverse
switch is /-NOLOAD.
Suppose the preprocessor, PRE, translates the file BAZ into a file FOO which
is a FAIL program. FOO must be translated when PRE is done. Also, MAIN and
SINE must be translated and loaded with FOO. The command:
LOAD FOO=BAZ/PROCESSOR PRE/NOLOAD,MAIN,SINE,FOO/FORWARD
will do all of this. The /FORWARD switch is necessary because the file FOO
does not exist at the time the command is given. Including the /FORWARD
switch prevents SNAIL from looking for FOO; SNAIL will assume that FOO
magically appears before FAIL is called. The inverse switch is /-FORWARD.
The processor DO (see Section 5.7 of the Monitor Command Manual, in file
MONCOM.BH[S,DOC]) is another example of an alternate processor. The DO
program writes the CM tmpcor file to force the exit-and-go command from the
editors to run DO again.
SNAIL: Translator Switches
Switch names enclosed in parentheses "(" and ")" are passed directly to the
translator. The documentation for each of the translators explains what
switches are available. The switches passed in this way appear on the
source file specification. Sometimes it is necessary to put switches on the
binary or listing term. For this purpose, there are two other switch
constructions.
The construction (#1,#2), where #1 and #2 are any switch strings, passes #1
to the binary term and #2 to the source term. The construction (#1,#2,#3)
passes #1 to the binary term, #2 to the listing term, and #3 to the source
term. For example,
COMPILE/LIST FOO(AX,BY,CZ)
will pass the switch string "AX" to the binary term, "BY" to the listing
term, and "CZ" to the source term.
SNAIL: Loader Switches
Switches to the loader may be specified in a COMPILE-class command.
Switches to LOADER appear as a percent sign (%) followed by a letter (or a
number and a letter) in the command string of one of the LOAD, TRY, EXECUTE,
PREPARE, or DEBUG commands; switches to LINK appear as a percent sign
followed by some character not appearing in the switch string, followed by
the switch string, followed by the character that appeared after the percent
sign. In either case, the switch string is directly specified to the
appropriate loader. Examples:
EXECUTE FOO1,FOO2,FOO3%M
TRY BIGPRG.SAI%100K
TRY/LINK BIGPRG.SAI%"RUNCOR:100"
LOADER and LINK switches are listed at the end of this document. For a full
description of what the other switches above mean, consult the DEC
documentation for LOADER and LINK. The LOADER has been modified for
Stanford, so the DEC documentation does not accurately reflect the state of
the software. Consult a wizard if necessary.
SNAIL: Command Files
COMPILE-class commands are sometimes too long to fit on one line, or are too
complex to be typed correctly every time. To solve this problem, arguments
can be read from a file. The text contained in such a file is read by SNAIL
as if it had been typed as the arguments to a command. The command file may
contain any features available in a COMPILE-class command. Any text between
a semicolon and the next line-feed is ignored; carriage-returns and
line-feeds are also ignored, and hence may not be used to separate file
names or other identifiers.
To use a term as a command file write an at sign (@) before the command file
name, e.g., LOAD @SYS. Upon scanning the at-sign followed by a file name,
SNAIL looks for a command file with that name; if no extension was
specified, SNAIL checks first for the file with extension .CMD, then for the
file with no extension and the specified name. The command file SYS might
look like the following file which is used to assemble the entire operating
system:
%S%B%? SYSTEM=HEAD(XLR)+OUTER+JOBDAT+ALLDAT+IMPDDB;
+LOWCOR+SYSMAK+PARSER+SYSINI+COMCSS+CLKSER+PAGSER;
+UUOCON+SPWSER+SCHEDU+SWPSER+CORE;
+DPYSER+TTYSER+LINED;
+DSKSER+DSKINT+DTCSER+MTCSER+FBPACK+TVSER+LPTSER+ELFSER+CARSER;
+XGPSER+PTPSER+PTRSER+DACSER;
+IMPCLK+IMPREG+IMPUUO+IMPINT;
+PATCH+DDT+ONCE
SNAIL: CREF Command
This command causes a cross-reference listing to be made. All the files
made from COMPILE-class commands which used the /CREF switch are processed;
for each such file, a cross-reference listing is generated in a file with
extension LST and the name of the file being processed. (LOGOUT makes SNAIL
forget which listing files to process.) The CREF command activates SNAIL
which in turn activates the CREF program in a special way. The CREF program
when activated in this way reads a file that SNAIL wrote which contains the
names of the files to process.
SNAIL: Switch Function Summary
A "-" in the column headed "*" means the switch can be negated; e.g.,
/-COMPILE is legal.
Switch Abbrev * Meaning
/BAIL /B Use BAIL if a debugger is required.
/COMPILE /COM - Force re-compilation without checking the dates of
REL files.
/CONLY /CON - Force re-compilation and produce only an extended
listing to be input to the CREF processor.
/CREF /C - Request a cross-reference listing.
/DDT /D Use DDT if a debugger is required.
/F4 /F4 - Use F40 (FORTRAN) for this term.
/FAIL /F - Use FAIL for this term.
/FORTRAN /FORT - Use F40 (FORTRAN) for this term.
/FORWARD /FORW - Prevent SNAIL from looking for this file to decide
if the REL file is up to date.
/LIBRARY /LIB - Force the loader to search this term as a library.
/LINK /LIN Use the LINK loader to create the core image.
/LIST /L - Request a listing file.
/LOADER /LOA Use the LOADER loader to create the core image.
/LONLY /LON - Force re-compilation and produce only a listing
file.
/MACRO /M - Use MACRO to translate this term.
/MAP /MAP Request a loader map of global symbols.
/NOCMFI /NOC Don't generate a CM command file for this command.
/NODMP /NOD Force re-loading without checking the dates of DMP
files.
/NOLOAD /NOL - Prevent a loading request for this term.
/NOSAISEG /NOS Load SAIL programs with the SAIL library instead of
the SAIL segment.
/PALX /PA - Use PALX to translate this term (produces .BIN
file).
/PROCESSOR /PR - Specify an alternate processor.
/RAID /RA Use RAID if a debugger is required.
/REL /RE - Force loading from the REL file if it exists.
/SAIL /S - Use SAIL to translate this term.
/SAVE /SAV Force the LOADER to make a DMP file of the core
image.
SNAIL: LOADER Switches and LINK Equivalents
LOADER LINK Meaning
Switch Equivalent
%A %"CONTENT:ZERO" Causes a listing of all global symbols to be
printed.
%B %"SYMSEG:LOW" BLT symbols down when done loading.
%1B BLT symbols to upper segment.
%C Chain beginning with Common.
%D %"TEST:DDT" Load DDT.
%E %"EXECUTE" Start up program when done loading.
%F %"SYSLIB" Enter library search mode; search all default
libraries.
%G %"GO" Finish loading, make final links, and exit.
%H %"DEBUG:RAID" Load and start RAID.
%I %"NOSTART" Ignore starting address of this program.
%J %"START" Use starting address of this program.
%nK %"RUNCOR:n" Adjust to n K of core (2n pages) when done
loading.
%L %"SEARCH" Search this file as a library.
%M %"MAP:END" Print storage map.
%N %"NOSEARCH" Leave library search mode.
%nO %"SET:.LOW.:n" Set program origin to n, absolute.
%P %"NOSYSLIB" Inhibit automatic library search for undefined
globals.
%Q %"SYSLIB" Allow automatic library search.
%R Chain beginning with resident module.
%S %"LOCALS" Load symbol table also.
%T %"DEBUG:DDT" Load and start DDT.
%U %"UNDEFINED" Print current list of undefined globals.
%V %"TRY:RAID" Load RAID.
%W %"NOLOCALS" Load without symbols.
%X %"CONTENT:NOZERO" Do not list all globals.
%Y Load SAILOW for 2 segment SAIL programs.
%Z %"RUN:LINK" Restart LOADER.
%< Disallow loading into upper segment.
%1< Allow loading into upper segment and load there
next.
%n< (n≥400000) Set upper segment relocation to n.
%-< Allow loading into upper segment and load in
lower next.
%? Sort symbols.
SNAIL: Error Messages
Obvious errors
No command file.
Incompatible commands.
You gave a command with no arguments, and either no command had been
saved or the two commands (the one you typed and the one which had
been saved) aren't compatible.
Unrecognizable file name.
No such device.
Unrecognizable processor name.
You mistyped a file or processor specifier.
Not a display.
You're trying to load the line-editor buffer and you're not using a
display.
Missing double-arrow or invalid core size.
Missing double-arrow.
The LOADBUF-type commands must always be followed by a double-arrow.
Too many files.
Currently the PUB and POX document compilers can only process one
document at a time.
File not found.
Either some file named in the command does not exist, or it doesn't
exist with the correct extension. You'll get this message if you
try to use the /FAIL switch with FOO.SAI, for instance.
Unknown command.
Command error.
Illegal character.
Something is wrong with what you typed, and SNAIL didn't find in the
command what it expected to find. For example, a file name didn't
follow an at-sign.
Nested brokets illegal.
Unbalanced brokets.
Can't use "=" with brokets.
You're not using brokets correctly. Each of the files within the
brokets will produce a different REL file, so the equal-sign
construct can't be used.
Unknown switch.
Negation of this switch not allowed.
Invalid switch string.
Illegal LOADER switch.
Illegal LINK switch.
Subtle errors
Empty command file.
Error in command file.
Tmpcor file too big.
The CM command file which SNAIL is attempting to read is messed up
somehow.
Storage overflow.
Your command included too much of something (file names, device
names, alternate processor specifications, translator or loader
switches), or there are too many files in your directory that have
to be date-checked.
Horrible errors (a wizard should be consulted)
SNAIL bug.
SNAIL allocation error.
Typing CONTINUE followed by a carriage return when the latter
happens might work.
Can't open channel.
This is probably a bug in SNAIL.
Couldn't create file.
A disk file could not be written correctly. Possibly a file is
write protected or in use by some other job. Otherwise you may need
help.
UFD missing.
You are aliased to a non-existent disk area. Otherwise, you need a
wizard.